Implement the free and flag-gated latency audit findings - #1377

Summary

• Implements the free- and flag-gated findings from the 2026-07-28 latency audit, which was proposed as PR chore: organize dirty work from claude/latency-audit-f1cbcd #1312 and closed unmerged. That PR was closed because its additive-index migration lacked synchronized schema/drift proof; the closing note also said "compatible latency work is already on main", but verification on 6021f6d found none of the six applied changes had landed, and the audit document itself was absent, so its follow-ups were untracked anywhere.
• Adds Server-Timing preamble stages (auth/ratelimit/scope). This was the repo's largest measurement gap: /api/answer/stream — the route the UI actually calls — emitted no header at all, and /api/search emitted none either. Only pre-header stages appear on the stream route, because headers flush before the first SSE frame and routing in-stream durations through the SSE contract would put instrumentation inside a governed clinical payload (answer-stream-contract.ts:18-21 whitelists only progress/final/error).
• L1-2 — corrected after review. /api/answer threads signal: request.signal into resolveSearchScope, fixing a pre-existing defect where a client disconnect could not cancel scope's paginated queries even though search-scope.ts:200,328 always supported .abortSignal(...). The concurrency part of this finding was written, reviewed, and removed — see "Correction" below. Scope resolution runs behind rate-limit admission.
• L1-1: the shared-cache-hit path — the fastest path in the system — no longer awaits setCachedAnswer before responding, so serving a cached answer no longer requires a fresh documents query first. forceRefresh: true is deliberately kept: it is the mid-request staleness guard that discards the write when the corpus moves, and that constraint is now documented on the function itself.
• L2-6: three select("*") calls on document_table_facts narrowed to explicit projections, reusing the existing tableFactDetailProjection rather than duplicating it. This keeps the generated search_tsv tsvector and owner_id off the wire. The PATCH response shape is unchanged — the projection matches the TableFactRow DTO field for field.
• L2-9: /api/medications builds the governance map and the fields=index projection once at module scope instead of mapping every record on every anonymous request. Ranking still runs per query.
• L3-4 / L3-5: ten ssr: false dashboard surfaces rendered nothing between HTML arrival and chunk execution and now use the shared LoadingPanel primitive (role="status" plus an accessible label); the Supabase origin gains preconnect and dns-prefetch, since AuthProvider awaits a cross-origin getUser() on mount that every auth-gated fetch queues behind. Neither is held behind ledger #017, which governs payload decisions — a loading fallback ships zero bytes and a resource hint ships about sixty.
• Deliberately not implemented: the six canary-gated findings (each needs a live eval pair and explicit approval), the seven #017-gated findings (need live Web-Vitals evidence first), and the four the audit retired during verification. All are filed as ledger #098–#105.
• L2-3 / L2-5 SQL is authored, not applied. No migration file and no supabase/** change: the three CREATE INDEX CONCURRENTLY statements live in docs/operator-apply-performance-latency-remediation.md with the apply → mirror → regenerate → register ordering spelled out. Registering the index names in required_indexes first would turn the live health check red, and shipping the migration without the schema mirror is precisely what closed PR chore: organize dirty work from claude/latency-audit-f1cbcd #1312.
• L4-2 is retracted. The audit called the worker's triple image read "CONFIRMED with no fix evidence"; it is in fact a deliberate peak-memory trade-off already documented in place at worker/main.ts:866-869 and dispositioned as such by the 2026-07-01 audit. Recorded as a correction in #104 so a third audit does not resurrect it.

RAG impact: no retrieval behaviour change — the only src/lib/rag/** edits defer a process-local cache write off the response path and add a doc comment; no scoring, ordering, selection, alias, or citation logic is touched, and the mid-request staleness guard is preserved.

Correction — L1-2's concurrency was refuted on review (e52c25c)

An earlier revision of this PR started resolveSearchScope concurrently with the rate-limit RPC and aborted it on deny, and this description claimed a throttled caller "still costs nothing". That claim was wrong, as Codex review raised at P1 and I confirmed against the code.

resolveSearchScope returns without touching the database only when there are no filters and no explicit document ids (the early returns at search-scope.ts:242 and :253). With either present it enters the paginated documents loop at :269 plus the nested label loop — and an AbortSignal cancels the client request without un-executing a statement Postgres has already begun. Because filters is caller-controlled, a throttled caller could keep spending database capacity while collecting 429s. That is the opposite of what admission control is for, and the wrong direction against capacity-review.md:106-113, which names Postgres CPU under concurrency the first soft failure — the very argument this PR uses for why round-trip reduction has capacity value.

Scope now sits behind admission. What is kept from the original change is the threaded abort signal and the scope timing stage, both of which are independent of the overlap and correct on their own. tests/answer-route-preamble.test.ts is the guard the reviewer asked for: no scope call may begin while the limiter is pending, and a denied request sent with filters must dispatch none at all. Both cases were checked to fail against the overlapping shape rather than pass vacuously. The refutation and its precondition — a non-database admission gate ahead of the durable limiter — are recorded in the audit's L1-2 section and ledger #099 so a later latency pass does not rediscover it as an obvious win.

Verification

• npm run verify:pr-local — exit 0. Format, lint, typecheck, Test Files 418 passed (418) / Tests 4244 passed | 4 skipped (4248), production build ✓ Compiled successfully in 59s, Client bundle secret surface check passed., Offline RAG fixture and manifest validation passed (36 golden cases, 21 suites).
• npm run verify:cheap — exit 0 after the main merge and the L1-2 correction: Test Files 423 passed (423) / Tests 4278 passed | 4 skipped (4282).
• npm run check:branch-review-ledger — passed after the main merge, guarding the merge=union duplication risk that ledger #088 watches for.

UI verification not run: the UI change is ten loading fallbacks built from the existing shared LoadingPanel primitive plus two <link> resource hints, with no new markup, styling, layout, or motion. Per the agreed scope for this pass, npm run verify:ui is deferred and tracked in ledger #105, which also asks for confirmation that the preconnect reaches <head> on a live page.

npm run eval:retrieval:quality, eval:rag, eval:quality, check:supabase-project and verify:release were not run: all are provider-backed, and no retrieval, ranking, selection, chunking, scoring, or answer-generation behaviour changed. check:drift and drift:manifest were not run because supabase/** is untouched, so there is nothing to re-derive.

Note on the red PR required runs: the job log shows COVERAGE_RESULT: success, BUILD_RESULT: success, STATIC_RESULT: success, SAFETY_RESULT: success, DB_RESULT: success, and UI_RESULT: cancelled → ##[error]production-ui result was cancelled. That is ledger #095 — the aggregate calls require_success on production-ui, so a push that supersedes an in-flight run reports failure indistinguishably from a real one. No substantive job failed.

Risk and rollout

• Risk: Low. After the correction the /api/answer preamble is fully sequential, so this PR adds no concurrency to the answer path and no work to denied requests; the ordering is pinned by a test that fails against the overlapping shape. The cache-write deferral cannot change what is served — it moves a write that was already discarded on a staleness mismatch off the response path, and the discard condition is untouched. The narrowed projections were checked field-by-field against the consuming DTO. The medication memo caches only query-independent derivations of an already-memoised snapshot.
• Rollback: revert the commits. No migration, no schema change, no data change, no configuration change, so revert is complete and immediate.
• Provider or production effects: None. No OpenAI, Supabase, or hosted-CI call was made in producing or verifying this change. The operator SQL is documentation only and applies nothing.

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed

Notes on the above: no answer content, citation, verification, or governance logic is touched, so source-backed claims and conservative source-metadata behaviour are unchanged by construction. Narrowing the table-facts projections strictly reduces what leaves the server — it stops owner_id being returned on the PATCH response. The preconnect reads only the already-public NEXT_PUBLIC_SUPABASE_URL and emits nothing when that variable is absent, so demo mode is unaffected and no credential enters the client graph; the client bundle secret surface check passed. The Supabase target is unchanged because no Supabase configuration is touched at all. There is no change to clinical decision-support behaviour, so the SaMD classification is unaffected.

Notes

• Ledger #098–#105 are new and replace the #085–#092 numbering the original audit draft used; those IDs were taken by unrelated items before this landed. #016 gains the L3-1/L3-2/L3-3/L3-6/L3-7 detail and a correction to its Therapy Compass framing: those files are unversioned and served with an ETag, so repeat visits pay revalidation round trips rather than the full 3.16 MB, and the fix is content-hashed filenames rather than a bare Cache-Control line.
• The #017 exemption for L3-4/L3-5 is a deliberate reading, stated in both the audit and #105: #017 gates payload decisions, and a zero-byte fallback cannot be justified or refuted by a Lighthouse number.

🤖 Generated with Claude Code

https://claude.ai/code/session_01361jh3eYVjJCzXWjAhdZiF

Summary by CodeRabbit

• Performance
  • Improved anonymous medication catalogue responses by reusing precomputed index projections and governance mappings.
  • Added browser network warming (preconnect/dns-prefetch) and clarified therapy catalogue JSON behavior with ETag revalidation.
• Reliability
  • Strengthened /api/answer request admission, abort propagation, and error handling to avoid unnecessary downstream work.
  • Updated several ssr:false rendering paths to consistently show an accessible loading fallback.
• Tests
  • Expanded automated coverage for preamble behavior, abort signaling, and Server-Timing composition/order.
• Documentation
  • Updated latency audit findings, latency remediation runbook, branch review ledger, and outstanding-issues tracking with revised guidance and execution status.